home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / rcs56.zoo / rcs / man / co.txt < prev    next >
Encoding:
Text File  |  1992-01-26  |  14.2 KB  |  463 lines
  1.  
  2.  
  3.  
  4. CO(1)            Printed December 19, 1991            CO(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      co    - check    out RCS    revisions
  10.  
  11. SYNOPSIS
  12.      co    [options] file ...
  13.  
  14. DESCRIPTION
  15.      co    retrieves a revision from each RCS file    and stores it
  16.      into the corresponding working file.
  17.  
  18.      Pathnames matching    an RCS suffix denote RCS files;    all
  19.      others denote working files.  Names are paired as explained
  20.      in    ci(1).
  21.  
  22.      Revisions of an RCS file may be checked out locked    or
  23.      unlocked.    Locking    a revision prevents overlapping    updates.
  24.      A revision    checked    out for    reading    or processing (e.g.,
  25.      compiling)    need not be locked.  A revision    checked    out for
  26.      editing and later checkin must normally be    locked.     Checkout
  27.      with locking fails    if the revision    to be checked out is
  28.      currently locked by another user.    (A lock    may be broken
  29.      with rcs(1).)  Checkout with locking also requires    the
  30.      caller to be on the access    list of    the RCS    file, unless he
  31.      is    the owner of the file or the superuser,    or the access
  32.      list is empty.  Checkout without locking is not subject to
  33.      accesslist    restrictions, and is not affected by the presence
  34.      of    locks.
  35.  
  36.      A revision    is selected by options for revision or branch
  37.      number, checkin date/time,    author,    or state.  When    the
  38.      selection options are applied in combination, co retrieves
  39.      the latest    revision that satisfies    all of them.  If none of
  40.      the selection options is specified, co retrieves the latest
  41.      revision on the default branch (normally the trunk, see the
  42.      -b    option of rcs(1)).  A revision or branch number    may be
  43.      attached to any of    the options -f,    -I, -l,    -M, -p,    -q, -r,
  44.      or    -u.  The options -d (date), -s (state),    and -w (author)
  45.      retrieve from a single branch, the    selected branch, which is
  46.      either specified by one of    -f, ..., -u, or    the default
  47.      branch.
  48.  
  49.      A co command applied to an    RCS file with no revisions
  50.      creates a zero-length working file.  co always performs
  51.      keyword substitution (see below).
  52.  
  53. OPTIONS
  54.      -r[rev]
  55.       retrieves the    latest revision    whose number is    less than
  56.       or equal to rev. If rev indicates a branch rather than
  57.       a revision, the latest revision on that branch is
  58.       retrieved.  If rev is    omitted, the latest revision on
  59.       the default branch (see the -b option    of rcs(1)) is
  60.  
  61.  
  62.  
  63. Page 1                     TARGON /35     Operating System
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CO(1)            Printed December 19, 1991            CO(1)
  71.  
  72.  
  73.  
  74.       retrieved.  If rev is    $, co determines the revision
  75.       number from keyword values in    the working file.
  76.       Otherwise, a revision    is composed of one or more
  77.       numeric or symbolic fields separated by periods.  The
  78.       numeric equivalent of    a symbolic field is specified
  79.       with the -n option of    the commands ci(1) and rcs(1).
  80.  
  81.      -l[rev]
  82.       same as -r, except that it also locks    the retrieved
  83.       revision for the caller.
  84.  
  85.      -u[rev]
  86.       same as -r, except that it unlocks the retrieved
  87.       revision if it was locked by the caller.  If rev is
  88.       omitted, -u retrieves    the revision locked by the
  89.       caller, if there is one; otherwise, it retrieves the
  90.       latest revision on the default branch.
  91.  
  92.      -f[rev]
  93.       forces the overwriting of the    working    file; useful in
  94.       connection with -q.  See also    FILE MODES below.
  95.  
  96.      -kkv Generate keyword strings using the default form, e.g.
  97.       $Revision: 5.7 $ for the Revision keyword.  A    locker's
  98.       name is inserted in the value    of the Header, Id, and
  99.       Locker keyword strings only as a file    is being locked,
  100.       i.e. by ci -l    and co -l.  This is the    default.
  101.  
  102.      -kkvl
  103.       Like -kkv, except that a locker's name is always
  104.       inserted if the given    revision is currently locked.
  105.  
  106.      -kk  Generate only    keyword    names in keyword strings; omit
  107.       their    values.     See KEYWORD SUBSTITUTION below.  For
  108.       example, for the Revision keyword, generate the string
  109.       $Revision$ instead of    $Revision: 5.7 $.  This    option is
  110.       useful to ignore differences due to keyword
  111.       substitution when comparing different    revisions of a
  112.       file.
  113.  
  114.      -ko  Generate the old keyword string, present in the working
  115.       file just before it was checked in.  For example, for
  116.       the Revision keyword,    generate the string $Revision:
  117.       1.1 $    instead    of $Revision: 5.7 $ if that is how the
  118.       string appeared when the file    was checked in.     This can
  119.       be useful for    binary file formats that cannot    tolerate
  120.       any changes to substrings that happen    to take    the form
  121.       of keyword strings.
  122.  
  123.      -kv  Generate only    keyword    values for keyword strings.  For
  124.       example, for the Revision keyword, generate the string
  125.       5.7 instead of $Revision: 5.7    $.  This can help
  126.  
  127.  
  128.  
  129. Page 2                     TARGON /35     Operating System
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CO(1)            Printed December 19, 1991            CO(1)
  137.  
  138.  
  139.  
  140.       generate files in programming    languages where    it is
  141.       hard to strip    keyword    delimiters like    $Revision: $ from
  142.       a string.  However, further keyword substitution cannot
  143.       be performed once the    keyword    names are removed, so
  144.       this option should be    used with care.     Because of this
  145.       danger of losing keywords, this option cannot    be
  146.       combined with    -l, and    the owner write    permission of the
  147.       working file is turned off; to edit the file later,
  148.       check    it out again without -kv.
  149.  
  150.      -p[rev]
  151.       prints the retrieved revision    on the standard    output
  152.       rather than storing it in the    working    file.  This
  153.       option is useful when    co is part of a    pipe.
  154.  
  155.      -q[rev]
  156.       quiet    mode; diagnostics are not printed.
  157.  
  158.      -I[rev]
  159.       interactive mode; the    user is    prompted and questioned
  160.       even if the standard input is    not a terminal.
  161.  
  162.      -ddate
  163.       retrieves the    latest revision    on the selected    branch
  164.       whose    checkin    date/time is less than or equal    to date.
  165.       The date and time may    be given in free format.  The
  166.       time zone LT stands for local    time; other common time
  167.       zone names are understood.  For example, the following
  168.       dates    are equivalent if local    time is    January    11, 1990,
  169.       8pm Pacific Standard Time, eight hours west of
  170.       Coordinated Universal    Time (UTC):
  171.  
  172.            8:00 pm lt
  173.            4:00 AM,    Jan. 12, 1990        note: default is UTC
  174.            1990/01/12 04:00:00        RCS date format
  175.            Thu Jan 11 20:00:00 1990    LT    output of ctime(3) + LT
  176.            Thu Jan 11 20:00:00 PST 1990    output of date(1)
  177.            Fri Jan 12 04:00:00 GMT 1990
  178.            Thu, 11 Jan 1990    20:00:00 -0800
  179.            Fri-JST,    1990, 1pm Jan 12
  180.            12-January-1990,    04:00-WET
  181.  
  182.       Most fields in the date and time may be defaulted.  The
  183.       default time zone is UTC.  The other defaults    are
  184.       determined in    the order year,    month, day, hour, minute,
  185.       and second (most to least significant).  At least one
  186.       of these fields must be provided.  For omitted fields
  187.       that are of higher significance than the highest
  188.       provided field, the time zone's current values are
  189.       assumed.  For    all other omitted fields, the lowest
  190.       possible values are assumed.    For example, the date 20,
  191.       10:30    defaults to 10:30:00 UTC of the    20th of    the UTC
  192.  
  193.  
  194.  
  195. Page 3                     TARGON /35     Operating System
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CO(1)            Printed December 19, 1991            CO(1)
  203.  
  204.  
  205.  
  206.       time zone's current month and    year.  The date/time must
  207.       be quoted if it contains spaces.
  208.  
  209.      -M[rev]
  210.       Set the modification time on the new working file to be
  211.       the date of the retrieved revision.  Use this    option
  212.       with care; it    can confuse make(1).
  213.  
  214.      -sstate
  215.       retrieves the    latest revision    on the selected    branch
  216.       whose    state is set to    state.
  217.  
  218.      -w[login]
  219.       retrieves the    latest revision    on the selected    branch
  220.       which    was checked in by the user with    login name login.
  221.       If the argument login    is omitted, the    caller's login is
  222.       assumed.
  223.  
  224.      -jjoinlist
  225.       generates a new revision which is the    join of    the
  226.       revisions on joinlist. This option is    largely    obsoleted
  227.       by rcsmerge(1) but is    retained for backwards
  228.       compatibility.
  229.  
  230.       The joinlist is a comma-separated list of pairs of the
  231.       form rev2:rev3, where    rev2 and rev3 are (symbolic or
  232.       numeric) revision numbers.  For the initial such pair,
  233.       rev1 denotes the revision selected by    the above options
  234.       -f, ..., -w.    For all    other pairs, rev1 denotes the
  235.       revision generated by    the previous pair.  (Thus, the
  236.       output of one    join becomes the input to the next.)
  237.  
  238.       For each pair, co joins revisions rev1 and rev3 with
  239.       respect to rev2. This    means that all changes that
  240.       transform rev2 into rev1 are applied to a copy of rev3.
  241.       This is particularly useful if rev1 and rev3 are the
  242.       ends of two branches that have rev2 as a common
  243.       ancestor.  If    rev1<rev2<rev3 on the same branch,
  244.       joining generates a new revision which is like rev3,
  245.       but with all changes that lead from rev1 to rev2
  246.       undone.  If changes from rev2    to rev1    overlap    with
  247.       changes from rev2 to rev3, co    reports    overlaps as
  248.       described in merge(1).
  249.  
  250.       For the initial pair,    rev2 may be omitted.  The default
  251.       is the common    ancestor.  If any of the arguments
  252.       indicate branches, the latest    revisions on those
  253.       branches are assumed.     The options -l    and -u lock or
  254.       unlock rev1.
  255.  
  256.      -Vn  Emulate RCS version n, where n may be    3, 4, or 5.  This
  257.       may be useful    when interchanging RCS files with others
  258.  
  259.  
  260.  
  261. Page 4                     TARGON /35     Operating System
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CO(1)            Printed December 19, 1991            CO(1)
  269.  
  270.  
  271.  
  272.       who are running older    versions of RCS.  To see which
  273.       version of RCS your correspondents are running, have
  274.       them invoke rlog on an RCS file; if none of the first
  275.       few lines of output contain the string branch: it is
  276.       version 3; if    the dates' years have just two digits, it
  277.       is version 4;    otherwise, it is version 5.  An    RCS file
  278.       generated while emulating version 3 will lose    its
  279.       default branch.  An RCS revision generated while
  280.       emulating version 4 or earlier will have a timestamp
  281.       that is off by up to 13 hours.  A revision extracted
  282.       while    emulating version 4 or earlier will contain dates
  283.       of the form yy/mm/dd instead of yyyy/mm/dd and may also
  284.       contain different white space    in the substitution for
  285.       $Log$.
  286.  
  287.      -xsuffixes
  288.       Use suffixes to characterize RCS files.  See ci(1) for
  289.       details.
  290.  
  291. KEYWORD    SUBSTITUTION
  292.      Strings of    the form $keyword$ and $keyword:...$ embedded in
  293.      the text are replaced with    strings    of the form
  294.      $keyword:value$ where keyword and value are pairs listed
  295.      below.  Keywords may be embedded in literal strings or
  296.      comments to identify a revision.
  297.  
  298.      Initially,    the user enters    strings    of the form $keyword$.
  299.      On    checkout, co replaces these strings with strings of the
  300.      form $keyword:value$.  If a revision containing strings of
  301.      the latter    form is    checked    back in, the value fields will be
  302.      replaced during the next checkout.     Thus, the keyword values
  303.      are automatically updated on checkout.  This automatic
  304.      substitution can be modified by the -k options.
  305.  
  306.      Keywords and their    corresponding values:
  307.  
  308.      $Author$
  309.       The login name of the    user who checked in the    revision.
  310.  
  311.      $Date$
  312.       The date and time (UTC) the revision was checked in.
  313.  
  314.      $Header$
  315.       A standard header containing the full    pathname of the
  316.       RCS file, the    revision number, the date (UTC), the
  317.       author, the state, and the locker (if    locked).
  318.  
  319.      $Id$ Same as $Header$, except that    the RCS    filename is
  320.       without a path.
  321.  
  322.      $Locker$
  323.       The login name of the    user who locked    the revision
  324.  
  325.  
  326.  
  327. Page 5                     TARGON /35     Operating System
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. CO(1)            Printed December 19, 1991            CO(1)
  335.  
  336.  
  337.  
  338.       (empty if not    locked).
  339.  
  340.      $Log$
  341.       The log message supplied during checkin, preceded by a
  342.       header containing the    RCS filename, the revision
  343.       number, the author, and the date (UTC).  Existing log
  344.       messages are not replaced.  Instead, the new log
  345.       message is inserted after $Log:...$.    This is    useful
  346.       for accumulating a complete change log in a source
  347.       file.
  348.  
  349.      $RCSfile$
  350.       The name of the RCS file without a path.
  351.  
  352.      $Revision$
  353.       The revision number assigned to the revision.
  354.  
  355.      $Source$
  356.       The full pathname of the RCS file.
  357.  
  358.      $State$
  359.       The state assigned to    the revision with the -s option
  360.       of rcs(1) or ci(1).
  361.  
  362. FILE MODES
  363.      The working file inherits the read    and execute permissions
  364.      from the RCS file.     In addition, the owner    write permission
  365.      is    turned on, unless -kv is set or    the file is checked out
  366.      unlocked and locking is set to strict (see    rcs(1)).
  367.  
  368.      If    a file with the    name of    the working file exists    already
  369.      and has write permission, co aborts the checkout, asking
  370.      beforehand    if possible.  If the existing working file is not
  371.      writable or -f is given, the working file is deleted without
  372.      asking.
  373.  
  374. FILES
  375.      co    accesses files much as ci(1) does, except that it does
  376.      not need to read the working file.
  377.  
  378. ENVIRONMENT
  379.      RCSINIT
  380.       options prepended to the argument list, separated by
  381.       spaces.  See ci(1) for details.
  382.  
  383. DIAGNOSTICS
  384.      The RCS pathname, the working pathname, and the revision
  385.      number retrieved are written to the diagnostic output.  The
  386.      exit status is zero if and    only if    all operations were
  387.      successful.
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Page 6                     TARGON /35     Operating System
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. CO(1)            Printed December 19, 1991            CO(1)
  401.  
  402.  
  403.  
  404. IDENTIFICATION
  405.      Author: Walter F. Tichy.
  406.      Revision Number: 5.7; Release Date: 1991/08/19.
  407.      Copyright O 1982, 1988, 1989 by Walter F. Tichy.
  408.      Copyright O 1990, 1991 by Paul Eggert.
  409.  
  410. SEE ALSO
  411.      ci(1), ctime(3), date(1), ident(1), make(1), rcs(1),
  412.      rcsdiff(1), rcsintro(1), rcsmerge(1), rlog(1), rcsfile(5)
  413.      Walter F. Tichy, RCS--A System for    Version    Control,
  414.      Software--Practice    & Experience 15, 7 (July 1985),    637-654.
  415.  
  416. LIMITS
  417.      Links to the RCS and working files    are not    preserved.
  418.  
  419.      There is no way to    selectively suppress the expansion of
  420.      keywords, except by writing them differently.  In nroff and
  421.      troff, this is done by embedding the null-character \& into
  422.      the keyword.
  423.  
  424. BUGS
  425.      The -d option sometimes gets confused, and    accepts    no date
  426.      before 1970.
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459. Page 7                     TARGON /35     Operating System
  460.  
  461.  
  462.  
  463. ə